home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Aminet 1 (Walnut Creek)
/
Aminet - June 1993 [Walnut Creek].iso
/
aminet
/
dev
/
debug
/
debugger.lzh
/
debugdoc
< prev
next >
Wrap
Text File
|
1989-10-15
|
23KB
|
710 lines
-- Amiga Debugger --
Debug v2.10
Software and documentation by Jim Thibodeau and Larry LaPlume. Debug
is the official resident debugger here at SLADE Software.
This is the second release of this program. Some of the added features
include symbolic dissasembly, breakpoint toggling, workbench startup
and simple expression parsing. As before, we welcome your comments and
suggestions, and you can reach us like this:
Jim Thibodeau Larry Laplume
35349 Janine Dr. 64 Garland Dr. #4
Zephyrhills, FL. 33541 Jackson, TN. 38301
(813) 788-2627 (901) 664-7059
-- Debug Notes --
Command line syntax:
Is geared toward the heavy duty hacker. Generally, a command
line consists of a single letter command, an optional space, and
1 or two arguments. Arguments may be numeric, symbolic, contain
the simple math operators +,-,/,*,<<,>>, a register, or a segment
number. The supported numeric formats are: Hexidecimal, decimal
or binary. Some commands take no arguments, such as eXit and
display Hunk list.
Note that Debug shares its very own Task Control Structure
with the program being debugged. Things that the program being
debugged does to its Task Control Structure, it automatically
does to Debug's Task Control Structure. Currently, Debug modifies
the TC_TRAPCODE field of the TCB, so if your program changes
this, Debug will NOT work.
When Disassembling or dumping memory, none, one or two
arguments may be given. If no argument is given, the operation
will begin where the last operation left off. If one argument is
given, the operation will begin at the address specified, and
continue for a few lines. If two arguments are given, the
operation will begin with the address specified by the first
argument, and continue to the second argument. The disassemble
and memory dump routines both support the ^C user break keystroke
to stop them from continuing to their normal completion.
When Debug is ready to accept commands it will display
a minus sign as a prompt. Commands may then be typed at the
keyboard, followed by the return or enter keys on the Amiga
keyboard. Most of the time, spaces are optional, except where the
parser may become confused. For example:
-g_main _exit Will begin execution at _main, and quit at _exit.
-g_main_exit Will attempt to begin execution at _main_exit.
-- Expressions --
An expression is defined as 1 or more operands and 0 or more
operators. An operator is one of the following: +, -, *, /, <<,
or >>, and valid operands are as follows:
s<segment-number> The first executable address of the seg-
ent. This will be the same value as the
the segment using the 'S' command.
(<reg>[,<reg>]) Note that the second register is optional
but the first is not. This MUST be in
parentheses!
$<hex-num> A hexidecimal number.
+|-<dec-num> A signed decimal number. Because Hex is
default, you must specify either + or -.
%<binary-num> A binary number.
<number> A hexidecimal number. (The default).
<symbol> A symbolic label contained in the program
being debugged.
'<character>' A single character enclosed in quotes.
'<string>' A string of ascii characters enclosed in single
quotes.
Each element will be checked for correct syntax before a value
is returned. If the parser finds any errors, it will print a
(hopefully) helpful error message and terminate the command.
Valid registers are as follows. Note that they can be in either
upper or lower case.
a0-a7, d0-d7, sp, sr, pc, z, x, n, c, v.
Symbols are treated in a case-sensitive way to maintain
compatibility with the assembler. If the label _main is used in
your program, it must be referred to in lower case only.
Hexidecimal is the default input radix. If you type 3210, it is
evaluated as hexidecimal, not decimal. To specify decimal, you
must put a + or - in front of the number.
Because parentheses are used to delimit registers, no
expression nesting is allowed - i.e. 3 + (4*8) is illegal.
Operator precedence is as follows:
Highest Lowest
*,/ +,- <<, >>
There are no unary operators at this time.
-- Command Summary --
Note: The following symbols and their definitions are used
throughout this discussion:
| - or
[] - optional argument
<> - description - replace with value
Command: B (Breakpoint commands)
Syntax: b|B [s|c|x|t|<bp-number>] <bp-number> <expression>
Discussion:
Debug supports limited, multiple break points. Up to 8 break
points may be active at once. Use the -b command to view, set, or
clear any or all break points. When setting a break point,
Debug stores the requested address of a break point, stores
the contents of that address, and replaces it with
the MC68000's ILLEGAL opcode. Clearing the break point replaces
the ILLEGAL instruction with the saved contents. When the Amiga
attempts to execute the installed ILLEGAL instruction, via the
'g', 't', or 'z' commands, Debug considers it a breakpoint and
displays the appropriate information. New to this version is the
toggle subcommand. By using this once, the breakpoint is still
set, but disabled (i.e. it will not cause the program to stop
executing). By using it again, the breakpoint is enabled. Note
that disabled breakpoints will not show up in the dissasembly.
Examples:
-b Lists all currently set break points.
-b 1 List the current status of break point number
one.
-bs 1 100 Sets Break point number one to address $100.
-bc 1 Removes break point one, and restores saved
contents of that address.
-bx Remove all of the eight break points that are
set.
-bt 0 If breakpoint 0 is enabled, disable it and vice/
versa.
Command: C (Set Command Line Tail)
Syntax: c|C [<parameter string>]
Example:
-c Desired Command line tail
Declare "Desired Command line tail" as a command tail.
Debug will set up the string in memory, and install a pointer
to it and the length of the specified string in the MC68000s' A0
and D0 registers each time, BUT NOT UNTIL the registers are
initialized. (See the "I" command).
Command: D (Disassemble memory)
Syntax: d|D [<start-address>] [<end-address>]
Examples:
-d 100 200 Will disassemble memory from address $100 to
$200.
-d (a0) Disassemble memory pointed to by the contents of
register A0.
-d (pc) Disassemble memory at the value of the Program
Counter.
-d (a0,d0) Disassemble memory at the value of the register
A0 plus the contents of the D0 register. This is
similar to the processor's d(An,Xi) mode except
for the lack of index size specifier - the size
always being long, and the lack of any dis-
placement value.
Command: f (Fill memory)
Syntax: f.|F. <size> <start-address> <end-address> <value list>
Discussion:
This command fills successive memory locations from start-
address to end-address with the values in value-list. As with
the modify command, valid size specifiers are B, W and L.
Examples:
-f.l $4000 $5000 = 0
Fill memory between addresses $4000 and $5000
with zeros.
-f.b $4000 $5000 = 7, 'This is a test...', 0
Fill memory with a stupid, repeating, flashing,
NULL terminated message.
Command: G (Go execute instructions)
Syntax: g|G [=<start-address>] [<end-address>]
Examples:
-g_main Execute the program until the label _main. This
is accomplished by setting a temporary breakpoint
at the destination address. If processing halts
before _main, the breakpoint will be cleared any-
way - so if you still wanted to go to _main, you
would have to type g_main again, not just g.
-g=100 Begin executing instructions at address $100.
-g Begin executing instructions at the current
program counter.
Command: H (Show Segment list of loaded file)
Syntax: h|H
Example:
-h Display segment list of current file.
Command: I (Initialize MC68000 Registers)
Syntax: i|I
Discussion:
When initializing, Command line tail values (if any) are
installed in registers A0 and D0. Also initialized are the
Program Counter, and User Stack Pointer registers. When
initializing the USP, the top of stack is found, then the address
of a termination routine is pushed onto the stack, so the program
can run to its completion, and remain in Debug for further
examination.
* * * N O T E * * *
The following conditions AUTOMATICALLY perform the "I"
command:
1. Normal termination of the program. (registers are displayed
before reset).
2. Attempting to Load a file. (even if the load fails).
Example:
-i Initialize ALL MC68000 register values.
Command: L (Load a file for debugging)
Syntax: l|L [<path>/]<filespec> [<arguments>]
Example:
-l fred abc Will attempt to read the file fred, and set its
arguments to the string 'abc'.
Command: M (Memory dump)
Syntax: m|M [<start-address>] [<end-address>]
m|M [B|W|L]
Discussion:
This command presently only dumps data as longwords. As noted
in the version changes above, dumping will proceed from an odd
address if specified.
Examples:
-m 100 200 Display memory contents from address $100 to $200
-m (sp) Display memory contents pointed to by the stack
pointer.
-mb Change future memory dumps to eight bit format (byte).
-mw Change future memory dumps to sixteen bit format (word).
-ml Change future memory dumps to thirty-two bit format (long).
Command: N (Change default input radix)
Syntax: n|N [<H|D|B>]
Discussion:
Debug initially uses hexidecimal as the default input radix. This may
be changed to Decimal or Binary, by using the "n" command. Note that typing
$, +, -, or % before any argument will override the default radix.
Example:
-nd Changes the default input radix to decimal.
Command: R (Display/Set MC68000 Register/Flag values)
Syntax: r|R [<register>]
Examples:
-r Display the contents of MC68000 registers.
-ra0 _main Set register a0 to the address of _main.
-r a0 100 Load register A0 with the value $100.
-r d0 +100 Loads register D0 with the decimal value +100.
-r d0 -1 Loads register d0 with the decimal value of -1.
-r sr %101 Loads the Status Register with the binary value
%101.
-r z 1 Forces the Zero flag on.
Command: S (Display symbols)
Syntax: s|S [g|<symbol>]
Examples:
-s Display all of the symbols.
-sg Just display the global symbols. A local symbol
is defined as one containing a '$'.
-s_fred Display _fred and its address.
Command: T (Execute in Trace mode)
Syntax: t|T [=<start-address>] [<trace-count>]
Discussion:
Trace works just like Go, except that only ONE instruction is
executed, and a register frame is displayed AFTER the instruction
executes. Additionally, Debug will disassemble the next
instruction to be executed. A trap number of 9 will usually
appear when tracing.
Note that due to characteristics of the Amiga's multitasking
system, attempting to trace certain types of processor errors,
including zero divide condition, can, and probably will crash the
entire system.
Examples:
-t=_main Trace the instruction at _main.
-t=ralph 4 Trace 4 instructions beginning at the label
ralph.
-t4 Trace 4 instructions beginning at the current
program counter.
Command: W (Toggle private window on/off).
Syntax: w|W
Discussion:
When Debug is initially loaded, all I/O uses this window. Using
it once, forces Debug to use _stdin and _stdout for its I/O. If
the program being debugged uses _stdin and _stdout and Debug is
using the window, the system WILL hang up when trying to do a
Read(), therefore, use the 'w' command before beginning
execution. Note that this command does nothing if Debug is
run from the workbench because a workbench program has no default
I/O handles. Note that this window uses the CON: device.
Example:
-w Close private window if it's open, Open private
window if it's closed.
Command: X (eXit Debug)
Syntax: x|X
Example:
-x Bye bye!
Command: Z (Zip through a subroutine)
Syntax: z|Z
Discussion:
Zip is useful when tracing code. When the next instruction to
be executed is a BSR or a JSR and tracing through the subroutine
is not desirable, just press "z". Debug will attempt to
execute the subroutine, and stop at the instruction immediately
following it. Zip performs this feat of magic by setting a temp-
orary breakpoint after the next instruction. Zip is also handy
for skipping loops: just trace to the bottom of the loop, and
type Z - Zip will execute up to the instruction following the
loop.
Example:
-z Zip through instruction at the current Program
counter.
Command: . (Modify memory)
Syntax: . <size> <start-address> = <value list>
Discussion:
The modify memory command will insert the values in the value
list in memory starting at the start address. The size specifier
is the familiar B, W or L, and each value in the value list must
be separated by commas.
Examples:
-.b $4000 = 1, 2, 3, 4, 5, 6, 7, 8, 9, a
Writes the values 1 to 10 at successive memory
locations starting at address $4000.
-.w _main = 1, 2, 3, 4, 5
Writes the values 1 to 5 at every OTHER address
starting at the address of the symbol _main.
-.l $4000 = 1, 2, 3, 4, 5
Writes the values 1 to 5 as 32 bit values
beginning at address $4000.
-.b $4000 = 'Fred''s dog' 10 'has fleas.', 0
Stores the string:
"Fred's dog
has fleas"
at address $4000 complete with an embedded
linefeed and (') character.
Command: . (Modify memory)
Syntax: . <size> <start-address> = <value list>
Discussion:
The modify memory command will insert the values in the value
list in memory starting at the start address. The size specifier
is the familiar B, W or L, and each value in the value list must
be separated by commas.
Examples:
-.b $4000 = 1, 2, 3, 4, 5, 6, 7, 8, 9, a
Writes the values 1 to 10 at successive memory
locations starting at address $4000.
-.w _main = 1, 2, 3, 4, 5
Writes the values 1 to 5 at every OTHER address
starting at the address of the symbol _main.
-.l $4000 = 1, 2, 3, 4, 5
Writes the values 1 to 5 as 32 bit values
beginning at address $4000.
-.b $4000 = 'Fred''s dog' 10 'has fleas.', 0
Stores the string:
"Fred's dog
has fleas"
at address $4000 complete with an embedded
linefeed and (') character.
Command: > (Redirect output to a file)
Syntax: > [<Filename>]
Discussion:
The > command may be used to direct all of debug's output to a file, if
desired. To restore console output use the > command with no paramaters.
Note that all output including prompts, are redirected until normal output
is restored.
Examples:
->ram:temp Directs all debug output to the file "temp" on the ramdisk.
->SER: Sends all debug output to the Amiga serial port.
-> Restores the normal output stream.
Command: < (Get input from a file)
Syntax: < [<Filename>]
Discussion:
Debug may be used in non-interactive mode via the < command. In this
case, a file is specified. The file is read, and interperted exactly as
if the contents of the file were typed on the keyboard. At the end of the
file, debug will terminate unless the default input stream is restored via
the < command with no paramaters WITHIN the file. Note that any or all
commands may be used in script files written for debug. This feature is
useful for redundant debugging.
Examples:
-<DebugScriptFile Gets input from DebugScriptFile.
-<SER: Gets input from the Amiga's serial port.
< (Within a file) Restores default input.
Command: ? (Help)
Syntax: ?
Example:
-? Display the help message.
Command: = (Evaluate expression).
Syntax: = <expression>.
Discussion:
This command will evaluate the expression following the '='
and print the result in ascii, binary, hexidecimal and decimal.
Examples:
-= 1*2 Evaluate 1 * 2 and print it.
-= fred + 4 Evaluate fred + 4 and print the value.
-- Using symbols --
If you are developing with an assembler, you must use the
'-C S' or similar switch when assembling your program. This
switch puts the symbols from your program in the symbol hunks of
the executable file. (see the AmigaDOS manual for more inform-
ation on symbol hunks). No special software tool is required.
If you are developing in another language, see your language
reference for details on generating symbol hunks.
Unfortunately, if your language processor does not support
symbol hunks, Debug won't be able to use symbols.
-- Error messages --
- Segment out of range:
The segment number is greater than the number of segments
loaded. Use the 'S' command to see the segment list.
- Bad register:
The register was not recognized. See the section on
expressions for valid registers.
- Bad register number:
The digit after an 'a' register or 'd' register was not
recognizable or out of range.
- Bad number format:
The number typed in was illegal.
- Bad character format:
The character typed in was invalid.
- Symbol not found or bad number format:
The parser could not evaluate the element as a hex-
idecimal number or a symbol. To avoid confusion between a
hexidecimal number and a label, prefix the number with a
'$'.
- Missing expression:
This error usually occurs when a binary operator is
used with only 1 operand, or the '=' command is used with
no expression following it.
- No file loaded:
This error occurs when you specify a segment in an
expression, with no loaded file. If there is no file,
there is no segment list!
- Breakpoint number out of range:
Breakpoints must be in the range 0-7.
- No breakpoint to toggle:
Debug cannot enable or disable a breakpoint that is not
set.
- Pc MUST be word aligned:
To prevent accidental address errors, the program counter
is tested for word alignment each time it is set.
- Out of range for 16-bit number:
This error occurs when you try to set the status register
to a number greater than it will hold.
- Breakpoint not set:
This message is printed if you try to clear a breakpoint
that was not set.
- Symbol not found:
Either the symbol was mis-typed, or it is non-existant.
Remember that symbol names are case sensitive.
- Out of range for 8 bit number.
The number specified was > 255 or < -256
- Missing address.
The address was not specified for the '.' or the 'f'
command.
- Missing or invalid size specifier.
Valid size specifiers are: B(yte), W(ord) or L(ong).
- Operation MUST be word aligned.
For data sizes other than byte, the start address for the
'.' or 'f' command must be EVEN.
- No symbols loaded.
Either there is no file loaded (hence no symbols to
print), or your program contains no symbol hunks.
Consult your language reference on symbol hunks.
- No memory available.
Pretty much what you would expect from such a message -
no memory!
- <=> expected.
See the syntax for the '.' and 'f' commands.
- <,> expected.
See the syntax for the '.' and 'f' commands.
-- Bugs --
Some of the following are real bugs, others are just things
that may cause suprises to the unwary.
- The name of the program really belongs in the Task
control block of the debugger (which it shares). If you
are looking for it there, you won't find it.
- Even if no parameters are supplied to a program, AmigaDos
sticks the end-of-line character in a buffer and sets the
argument string length to 1. Debug does not. If there are
no parameters, D0 is 0, and A0 is 0.
- Debug's replacement Exit() function assumes that the
first three bytes of the library call are:
moveq #2,d0
bra.s xxx
If this changes in a future Dos library version, calling
calling Exit() from within Debug will probably crash the
system. Because Dos library is not implemented as a
'standard' jump table, Exec's SetFunction() doesn't work.
- Debug has unexplainedly crashed a few times, and it seems
to be a memory allocation/deallocation error. It may have
something to do with Metacomco's assembler, which has a
few bugs of its own. Any clues are welcome.
- Although Debug loads the registers so you can examine
BCPL code, something does not work right. Try loading
C:List, and typing G. Debug gets the initial registers
at startup, and saves them for the loaded program. Again
any clues are welcome.
- The command line arguments are terminated with an ascii
null character - not a newline ($10). Although it may
seem more consistent to end the line the way AmigaDOS
does, an end of file indicator will also terminate the
line (^\), so you should check for any value < ' ' for
a terminator in your debugging.
- Do not attempt to debug Debug. Because Debug changes the
TCB in a non-reentrant way, Debug has to be modified in
order for it to debug itself.
-- Future plans --
All (2) of us at SLADE software want to make this THE public
domain debugger. Toward this end, the next version will contain
a few more 'needed' features. If you have any ideas, or
commands you would like to see, let us know.
1. The addition of watch-point commands. These are similar to
breakpoints, but they trap on data writes instead of
executable instructions.
2. The ability to list symbols by segment number and hunk type.
3. The addition of the 'type' subcommand to dump.
4. The ability to use breakpoints and watchpoints in expressions.
They would have a syntax similar to segments.
5. Linked list traversal.
-- Addenda --
When displaying local symbols (symbols of the form nnn$), they
may have an extra 1 to 3 digits following them. This is the
'fault' of the Amiga assembler, not this program.
Some types of errors including zero divide, TRAP #x, and
address errors may alter the value of the program counter
displayed in the register frame. In other words, it may be
necessary to scan back a few bytes or words, with the
disassembler to view the offending instruction.